Claude Code 工程师使用指南

1. 快速上手

1.1 启动 Claude Code

# 在项目目录下启动
cd ~/projects/my-project
claude

# 指定提示词启动
claude "帮我实现一个用户认证模块"

# 带系统提示词启动
claude --system "你是一个资深 Go 工程师"

# 无头模式（CI/CD）
claude --print "运行测试并报告结果"

1.2 核心工作循环

1.3 首次使用推荐

2. 斜杠命令全览

2.1 核心命令

2.2 代码与项目命令

2.3 工作流命令

3. 权限模式

Claude Code 提供 5 种权限模式，控制工具执行前的审批行为：

3.1 切换模式

• 快捷键：Shift+Tab 快速切换
• 命令：/permissions 查看当前设置
• 配置：settings.json 中设置 permissions.defaultMode

3.2 工具级权限白名单

在 .claude/settings.json 中为常用只读操作配置白名单，减少审批提示：

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(ls:*)",
      "Bash(find:*)",
      "Bash(grep:*)"
    ]
  }
}

4. 键盘快捷键

4.1 会话控制

4.2 权限与配置

4.3 自定义快捷键

在 ~/.claude/keybindings.json 中自定义快捷键，支持 50+ 内置操作和 17 个不同的上下文：

{
  "bindings": [
    {
      "keys": ["ctrl+s"],
      "action": "submit",
      "context": "prompt"
    }
  ]
}

5. .claude 目录结构

.claude/ 目录是 Claude Code 的项目控制中心，包含 5 个子系统配置：

.claude/
├── CLAUDE.md              # 项目指令（自动加载到系统提示）
├── settings.json          # 项目级设置和权限（提交到 git）
├── settings.local.json    # 本地设置（不提交到 git）
├── keybindings.json       # 自定义键盘快捷键
├── agents/                # 自定义 Agent 定义
│   └── researcher.json
├── skills/                # 自定义技能定义
│   └── deploy-skill.json
├── memory/                # 持久化记忆文件
│   ├── MEMORY.md          # 记忆索引
│   ├── user_preferences.md
│   └── project_context.md
├── rules/                 # 详细规则文件
│   ├── coding-standards.md
│   └── testing-policy.md
├── commands/              # 自定义斜杠命令
│   └── deploy.md
└── plugins/               # 插件配置

5.1 用户级 vs 项目级

5.2 配置加载优先级

6. CLAUDE.md 配置

CLAUDE.md 是 Claude Code 的项目 README，启动时自动加载并注入系统提示。

6.1 最佳实践：路由文件模式

保持 CLAUDE.md 精简（< 150 行），作为路由文件指向 .claude/rules/*.md 中的详细规则：

# CLAUDE.md

## 项目概览
全栈 Web 应用，前端 React + TypeScript，后端 Node.js + PostgreSQL

## 技术栈
- 前端: React 18, TypeScript, TailwindCSS
- 后端: Node.js, Express, Prisma ORM
- 数据库: PostgreSQL 15
- 测试: Jest + Playwright

## 编码规范
- 前端组件使用函数式 + Hooks
- API 响应统一为 { data, error } 格式
- 数据库迁移使用 Prisma migrate

## 详细规则
- 代码规范: [.claude/rules/coding-standards.md](.claude/rules/coding-standards.md)
- 测试策略: [.claude/rules/testing-policy.md](.claude/rules/testing-policy.md)
- 部署流程: [.claude/rules/deployment.md](.claude/rules/deployment.md)

6.2 层级结构

CLAUDE.md 支持多层级文件，高层级覆盖低层级：

7. 项目记忆系统

Claude Code 通过 .claude/memory/ 目录实现跨会话持久记忆，分为四种类型：

7.1 记忆文件格式

---
name: no-db-mocking
description: 集成测试必须使用真实数据库
type: feedback
---

集成测试必须使用真实数据库，不能 mock。
**Why:** 上季度 mock/prod 差异导致迁移失败但测试通过。
**How to apply:** 所有 integration test 使用真实 PostgreSQL 实例。

7.2 MEMORY.md 索引

MEMORY.md 是记忆文件的索引，Claude 启动时加载此文件：

# 记忆索引

- [数据库测试偏好](no-db-mocking.md) — 集成测试不用 mock
- [用户背景](user-role.md) — 资深 Go 工程师，新项目学 Rust
- [合并冻结](merge-freeze.md) — 2026-04-29 后非关键 PR 暂停

7.3 什么不该存

• 代码模式、架构、文件路径 — 可以从代码本身读取
• Git 历史、谁改了什么 — git log 是权威来源
• 调试方案 — 修复已经在代码里了
• 临时任务细节 — 只在当前会话中相关

8. Hooks 自动化

Hooks 是 Claude Code 的自动化机制，在特定事件触发时执行 Shell 命令。由 Claude Code harness 执行，不是 LLM 本身。

8.1 配置方式

在 settings.json 或 settings.local.json 中配置：

{
  "hooks": {
    "PostToolUse": {
      "Write": "npx eslint --fix",
      "Edit": "npx prettier --write"
    },
    "PreToolUse": {
      "Bash": "echo '即将执行: $CLAUDE_TOOL_INPUT'"
    },
    "Notification": {
      "PostCommand": "say 'Claude 完成'"
    }
  }
}

8.2 可用 Hook 事件

9. MCP 服务集成

MCP（Model Context Protocol）让 Claude Code 连接外部工具：文件系统、API、数据库、开发工具等。

9.1 安装范围

9.2 配置示例

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/zdh/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

9.3 常用 MCP 服务

10. Agent 与 Teams

10.1 Agent 系统

Claude Code 支持派生专用 Agent 处理复杂任务。每种 Agent 有不同的工具集和能力：

10.2 Teams 团队协作

多个 Agent 组成 Team，共享任务列表，并行工作：

# Team 工作流程
1. TeamCreate — 创建团队和任务列表
2. TaskCreate — 创建结构化任务
3. Agent + team_name — 派生 Agent 加入团队
4. TaskUpdate + owner — 分配任务给 Agent
5. Agent 完成任务 → TaskUpdate + status:completed
6. 所有任务完成后 SendMessage 关闭团队

10.3 自定义 Agent

在 .claude/agents/ 中定义自定义 Agent：

// .claude/agents/frontend-reviewer.json
{
  "name": "frontend-reviewer",
  "description": "审查前端代码变更",
  "model": "sonnet",
  "instructions": "审查 React 组件代码，关注性能、可访问性和最佳实践。"
}

11. Plan Mode 规划模式

规划模式是处理复杂变更的最佳实践：先设计方案，再实施。

11.1 何时使用

• 新功能实现，涉及多个文件和模块
• 重构现有代码，可能影响多个功能
• 架构决策，需要在多个方案中选择
• 不确定的需求，需要先探索代码库

11.2 工作流

12. Skills 技能系统

Skills 是可复用工作流包，通过 /技能名 调用，组合提示词、指令和自定义工具。

12.1 可用技能

技能列表在会话中通过系统提醒消息显示。分为两类：

12.2 调用方式

# 调用内置技能
/review
/security-review
/init

# 调用自定义技能（需要显式调用）
/project-dir-manager
/remote-sync
/loop 5m /status

13. Settings 配置详解

13.1 settings.json 核心字段

v2.1 支持 60+ 设置项和 175+ 配置选项：

{
  "permissions": {
    "defaultMode": "default"
  },
  "hooks": {
    "PostToolUse": {
      "Write": "npx eslint --fix"
    }
  },
  "env": {
    "NODE_ENV": "development"
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  },
  "allowedTools": ["Bash", "Read", "Edit", "Write"],
  "disabledTools": ["Agent"],
  "model": "opus"
}

13.2 配置层次

14. 开发工作流最佳实践

14.1 高效提示词编写

14.2 推荐开发流程

14.3 多文件开发策略

• 独立变更：并行派生多个 Agent 同时处理
• 依赖变更：按顺序处理，先改底层再改上层
• 大规模重构：使用 Plan Mode 拆分步骤，逐步实施

14.4 测试驱动开发

# 推荐：先让 Claude 写测试，再实现功能
"为 UserService.createUser 写单元测试，包含正常路径和异常路径"
# 然后：运行测试看失败
"现在实现 createUser 让测试通过"
# 最后：确认所有测试通过
"运行测试确认全部通过"

15. 上下文管理策略

15.1 上下文窗口管理

Claude Code 有有限的上下文窗口。长对话会逐渐填满，需要管理：

• 自动压缩：Claude Code 在接近限制时自动压缩早期消息
• 手动压缩：使用 /compact 主动压缩，保留关键信息
• 新对话：使用 /clear 开始全新对话

15.2 何时压缩

15.3 信息留存策略

对话中的关键信息通过以下方式留存：

• CLAUDE.md：项目结构和规范，每次启动自动加载
• 记忆系统：用户偏好、项目决策、外部资源位置
• 代码本身：最重要的信息是代码本身，不需要额外记忆

16. Git 工作流集成

16.1 Claude Code 的 Git 操作

Claude Code 可以直接执行 Git 命令，但遵循安全协议：

• 不跳过 hook（--no-verify）
• 不强制 push（--force），除非用户明确要求
• 不修改 git config
• 创建新 commit 而非 amend，除非用户明确要求

16.2 推荐的 Git 工作流

# 1. 让 Claude 查看当前状态
"看看当前 git 状态"

# 2. 让 Claude 创建 commit
"把刚才的变更提交，写一个简洁的 commit message"

# 3. 审查 commit
"看看这个 commit 包含了什么"

# 4. 创建 PR（需要 gh CLI）
"创建一个 PR，标题简短，正文用 bullet points 描述变更"

# 5. 处理冲突
"这个分支和 main 有冲突，帮我解决"

16.3 Worktree 隔离

对于并行开发，使用 Git Worktree 隔离不同分支的工作：

• Claude Code 内置 EnterWorktree 支持
• 自动创建临时分支和工作目录
• 完成后自动清理或保留

17. 安全与权限

17.1 Claude Code 安全原则

• 默认安全：Default 模式下，危险操作需要确认
• 不执行不可信代码：Claude 不会直接运行从网上复制的代码
• 不暴露密钥：Claude 避免将敏感文件（.env、credentials）提交到 git
• OWASP 安全：Claude 避免引入 XSS、SQL 注入等常见漏洞

17.2 安全审查

在合并变更前运行 /security-review，检查：

• SQL 注入和参数化查询
• XSS 和输入验证
• 认证和授权绕过
• 敏感数据泄露
• 依赖安全问题

18. 性能优化

18.1 响应速度

18.2 避免的反模式

• 不要 sleep 轮询：用 run_in_background + 等待完成
• 不要重复搜索：Agent 的 Explore 模式结果复用
• 不要全量扫描：find 从 . 开始，不扫描整个文件系统
• 不要过度抽象：3 行相似代码优于半成品的抽象

19. Loop 与定时任务

19.1 Loop 循环执行

/loop 命令按固定间隔重复执行提示或命令：

# 每 5 分钟检查构建状态
/loop 5m 检查 CI 构建是否完成

# 每 10 分钟运行测试
/loop 10m /review

# 默认间隔 10 分钟
/loop /status

19.2 ScheduleWakeup 定时唤醒

更精细的定时控制，支持一次性或重复任务：

• 一次性：60s-3600s 范围内，适合"1 小时后提醒我"
• 重复：最小 60s，最大 3600s（1 小时）
• 自动过期：重复任务 7 天后自动过期

19.3 Cron 调度

通过 CronCreate 工具支持标准 5 字段 cron 表达式：

# 每个工作日 9am
"0 9 * * 1-5"

# 每 5 分钟
"*/5 * * * *"

# 今天下午 2:30 一次性
"30 14 29 4 *" (recurring: false)

20. 常见问题

Q: Claude Code 和 Claude API 有什么区别？

Claude Code 是 CLI 工具，内置文件操作、Shell 执行、Git 集成。Claude API 是原始 API，需要自己编写所有集成代码。

Q: Claude Code 能看到我整个代码库吗？

不会。Claude Code 按需读取文件，不会自动扫描整个代码库。对于大项目，建议让 Claude 搜索相关文件而不是读取全部。

Q: 如何保护敏感信息？

Claude Code 会避免将 .env、credentials.json 等敏感文件提交到 git。但最好的实践是确保这些文件已在 .gitignore 中。

Q: Claude 会记住什么？

对话历史在当前会话中保留。跨会话记忆通过 .claude/memory/ 持久化。CLAUDE.md 每次启动时自动加载。

Q: 如何让 Claude 更自主地工作？

切换到 Auto 权限模式，为常用只读操作配置权限白名单，使用 Hooks 实现自动化后处理。

Q: Claude Code 能用来做 CI/CD 吗？

可以。使用 --print 标志在无头模式下运行，或结合 GitHub Actions 等 CI 系统。

Q: 自定义斜杠命令怎么创建？

在 .claude/commands/ 目录下创建 .md 文件，或通过 Agent SDK 编程创建复杂命令。

Q: 如何选择模型？

通过 /config 或在 settings.json 中设置 "model": "opus" / "model": "sonnet" / "model": "haiku"。Opus 最强，Sonnet 平衡，Haiku 最快。